Events

None

Properties

AcceptFocus

Parent

Window

Methods

EmbedWithin

EmbedWithinPanel

Notes

To create a ContainerControl, add an instance of this class to your project. Do this either by clicking the Add Container Control button in the Project Editor toolbar or with the Project . Add . Add Container Control menu item. When you do so, REALbasic adds an instance of a ContainerControl to the project.

Double-click the ContainerControl item in the Project panel to open a Container Control Editor. The Container Control Editor looks like a Window Editor, except that it works only for ContainerControls. A ContainerControl doesn't have a Frame property (or a frame, for that matter), and has no Title bar, grow handle, or the other widgets that a window can have. The area of the ContainerControl is represented by a gray box.

The Container Control editor has the same Controls list as a Window Editor. Use it to add the controls or other ContainerControls to this ContainerControl.

When your design for the ContainerControl is complete, you can embed it in a window or control in either the IDE or via code. Multiple levels of embedding are supported.

In the IDE, you can embed the ContainerControl in the following way:

Switch to the Window Editor for the window that will contain the ContainerControl.

Use the popup menu above the list of controls to display the Project controls.

Add the ContainerControl to the window by dragging, double-clicking, or by clicking and drawing a region in the window.

Resize and reposition it as needed.

To add the ContainerControl to a window via code, use either the EmbedWithin or EmbedWithinPanel methods. Use EmbedWithin to embed the ContainerControl in either a window or a control, depending on whether the first parameter is a window or a control. For the special case of embedding within a PagePanel or a TabPanel, use EmbedWithinPanel instead. It allows you to pass the page number on which the ContainerControl will be embedded.

The following example uses a ContainerControl that has been added to the project.

You double-click a ContainerControl in the Project Window to display its ContainerControl Editor. Two checkboxes have been added.

The following statement embeds a ContainerControl at so that its top-left corner is 50 pixels from the left side of the window and 100 pixels from the top.

When the project is run, the controls in the ContainerControl appear in the default window, Window1. Use the same approach to embed the ContainerControl in a control other than a PagePanel or TabPanel; for the latter types of controls, use EmbedWithinPanel and pass the name of the control and the desired panel number.

Uses

ContainerControls have multiple uses, You can:

Organize groups of controls into reusable interface components,

Create custom controls made up of several constituent controls,

Increase encapsulation of complex window layouts,

Create dynamic layouts.

Behaviors

For the most part ContainerControls act exactly how you would expect. For example, if you put code in the MouseMove event of an embedded window, the event will fire when your mouse moves over the embedded window's boundaries. There are a few things you need to be aware of:

The Handle property of a ContainerControl and the Handle property of controls of an ContainerControl are Nil until the Open event. All of the other properties can be manipulated before the Open event.

ContainerControl either have their own keyboard focus and menu handling or they share it with their containing window. Which behavior is chosen depends on the state of the AcceptFocus flag when the window is embedded. When AcceptFocus is True, the ContainerControl does not share focus with the window. If a containing window has embedded that which share focus with it, those windows will get a first crack at handling it. If none handle it, the containing window will get a try. This applies to KeyDown and MenuCommands. It also affects how menu commands are enabled.

Some properties are new to ContainerControls and relate to its behavior when embedded; these behave like the corresponding properties of the Canvas control. These include the following: LockLeft, LockTop, LockRight, LockBottom, Enabled, AutoDeactivate, HelpTag, DisabledBalloonHelp, UseFocusRing, AcceptFocus, AcceptTabs, Parent and Window.

Miscellaneous Issues

The Moved, Resized, and Resizing events fire on embedded windows when the embedded window is moved or resized.

The Show/Hide and the Visible property can be used to set the visibility of embedded windows.

Nesting ContainerControls is allowed. However, you can't embed a ContainerControl such that the containing ContainerControl or a ContainerControl higher in the containing chain is another instance of the same ContainerControl; in other words, you can't recursively nest ContainerControls in other instances of themselves.

Nested ContainerControl coordinates for controls and events are automatically transformed for you. You don't need to worry about them unless you are dealing with global coordinates as you would for the MenuItem's Popup method.

The CancelClose event will fire for any ContainerControl or nested ContainerControls. Returning True from any of these ContainerControls will prevent the window or any of its controls from closing.

See Also

RectControl, Window classes.